home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / dgges.z / dgges
Encoding:
Text File  |  2002-10-03  |  10.1 KB  |  265 lines
  1.  
  2.  
  3.  
  4. DDDDGGGGGGGGEEEESSSS((((3333SSSS))))                                                            DDDDGGGGGGGGEEEESSSS((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      DGGES - compute for a pair of N-by-N real nonsymmetric matrices (A,B),
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      SUBROUTINE DGGES( JOBVSL, JOBVSR, SORT, DELCTG, N, A, LDA, B, LDB, SDIM,
  13.                        ALPHAR, ALPHAI, BETA, VSL, LDVSL, VSR, LDVSR, WORK,
  14.                        LWORK, BWORK, INFO )
  15.  
  16.          CHARACTER     JOBVSL, JOBVSR, SORT
  17.  
  18.          INTEGER       INFO, LDA, LDB, LDVSL, LDVSR, LWORK, N, SDIM
  19.  
  20.          LOGICAL       BWORK( * )
  21.  
  22.          DOUBLE        PRECISION A( LDA, * ), ALPHAI( * ), ALPHAR( * ), B(
  23.                        LDB, * ), BETA( * ), VSL( LDVSL, * ), VSR( LDVSR, * ),
  24.                        WORK( * )
  25.  
  26.          LOGICAL       DELCTG
  27.  
  28.          EXTERNAL      DELCTG
  29.  
  30. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  31.      These routines are part of the SCSL Scientific Library and can be loaded
  32.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  33.      directs the linker to use the multi-processor version of the library.
  34.  
  35.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  36.      4 bytes (32 bits). Another version of SCSL is available in which integers
  37.      are 8 bytes (64 bits).  This version allows the user access to larger
  38.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  39.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  40.      only one of the two versions; 4-byte integer and 8-byte integer library
  41.      calls cannot be mixed.
  42.  
  43. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  44.      DGGES computes for a pair of N-by-N real nonsymmetric matrices (A,B), the
  45.      generalized eigenvalues, the generalized real Schur form (S,T),
  46.      optionally, the left and/or right matrices of Schur vectors (VSL and
  47.      VSR). This gives the generalized Schur factorization
  48.  
  49.               (A,B) = ( (VSL)*S*(VSR)**T, (VSL)*T*(VSR)**T )
  50.  
  51.      Optionally, it also orders the eigenvalues so that a selected cluster of
  52.      eigenvalues appears in the leading diagonal blocks of the upper quasi-
  53.      triangular matrix S and the upper triangular matrix T.The leading columns
  54.      of VSL and VSR then form an orthonormal basis for the corresponding left
  55.      and right eigenspaces (deflating subspaces).
  56.  
  57.      (If only the generalized eigenvalues are needed, use the driver DGGEV
  58.      instead, which is faster.)
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DDDDGGGGGGGGEEEESSSS((((3333SSSS))))                                                            DDDDGGGGGGGGEEEESSSS((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      A generalized eigenvalue for a pair of matrices (A,B) is a scalar w or a
  75.      ratio alpha/beta = w, such that  A - w*B is singular.  It is usually
  76.      represented as the pair (alpha,beta), as there is a reasonable
  77.      interpretation for beta=0 or both being zero.
  78.  
  79.      A pair of matrices (S,T) is in generalized real Schur form if T is upper
  80.      triangular with non-negative diagonal and S is block upper triangular
  81.      with 1-by-1 and 2-by-2 blocks.  1-by-1 blocks correspond to real
  82.      generalized eigenvalues, while 2-by-2 blocks of S will be "standardized"
  83.      by making the corresponding elements of T have the form:
  84.              [  a  0  ]
  85.              [  0  b  ]
  86.  
  87.      and the pair of corresponding 2-by-2 blocks in S and T will have a
  88.      complex conjugate pair of generalized eigenvalues.
  89.  
  90.  
  91.  
  92. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  93.      JOBVSL  (input) CHARACTER*1
  94.              = 'N':  do not compute the left Schur vectors;
  95.              = 'V':  compute the left Schur vectors.
  96.  
  97.      JOBVSR  (input) CHARACTER*1
  98.              = 'N':  do not compute the right Schur vectors;
  99.              = 'V':  compute the right Schur vectors.
  100.  
  101.      SORT    (input) CHARACTER*1
  102.              Specifies whether or not to order the eigenvalues on the diagonal
  103.              of the generalized Schur form.  = 'N':  Eigenvalues are not
  104.              ordered;
  105.              = 'S':  Eigenvalues are ordered (see DELCTG);
  106.  
  107.      DELCTG  (input) LOGICAL FUNCTION of three DOUBLE PRECISION arguments
  108.              DELCTG must be declared EXTERNAL in the calling subroutine.  If
  109.              SORT = 'N', DELCTG is not referenced.  If SORT = 'S', DELCTG is
  110.              used to select eigenvalues to sort to the top left of the Schur
  111.              form.  An eigenvalue (ALPHAR(j)+ALPHAI(j))/BETA(j) is selected if
  112.              DELCTG(ALPHAR(j),ALPHAI(j),BETA(j)) is true; i.e. if either one
  113.              of a complex conjugate pair of eigenvalues is selected, then both
  114.              complex eigenvalues are selected.
  115.  
  116.              Note that in the ill-conditioned case, a selected complex
  117.              eigenvalue may no longer satisfy DELCTG(ALPHAR(j),ALPHAI(j),
  118.              BETA(j)) = .TRUE. after ordering. INFO is to be set to N+2 in
  119.              this case.
  120.  
  121.      N       (input) INTEGER
  122.              The order of the matrices A, B, VSL, and VSR.  N >= 0.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. DDDDGGGGGGGGEEEESSSS((((3333SSSS))))                                                            DDDDGGGGGGGGEEEESSSS((((3333SSSS))))
  137.  
  138.  
  139.  
  140.      A       (input/output) DOUBLE PRECISION array, dimension (LDA, N)
  141.              On entry, the first of the pair of matrices.  On exit, A has been
  142.              overwritten by its generalized Schur form S.
  143.  
  144.      LDA     (input) INTEGER
  145.              The leading dimension of A.  LDA >= max(1,N).
  146.  
  147.      B       (input/output) DOUBLE PRECISION array, dimension (LDB, N)
  148.              On entry, the second of the pair of matrices.  On exit, B has
  149.              been overwritten by its generalized Schur form T.
  150.  
  151.      LDB     (input) INTEGER
  152.              The leading dimension of B.  LDB >= max(1,N).
  153.  
  154.      SDIM    (output) INTEGER
  155.              If SORT = 'N', SDIM = 0.  If SORT = 'S', SDIM = number of
  156.              eigenvalues (after sorting) for which DELCTG is true.  (Complex
  157.              conjugate pairs for which DELCTG is true for either eigenvalue
  158.              count as 2.)
  159.  
  160.      ALPHAR  (output) DOUBLE PRECISION array, dimension (N)
  161.              ALPHAI  (output) DOUBLE PRECISION array, dimension (N) BETA
  162.              (output) DOUBLE PRECISION array, dimension (N) On exit,
  163.              (ALPHAR(j) + ALPHAI(j)*i)/BETA(j), j=1,...,N, will be the
  164.              generalized eigenvalues.  ALPHAR(j) + ALPHAI(j)*i, and
  165.              BETA(j),j=1,...,N are the diagonals of the complex Schur form
  166.              (S,T) that would result if the 2-by-2 diagonal blocks of the real
  167.              Schur form of (A,B) were further reduced to triangular form using
  168.              2-by-2 complex unitary transformations.  If ALPHAI(j) is zero,
  169.              then the j-th eigenvalue is real; if positive, then the j-th and
  170.              (j+1)-st eigenvalues are a complex conjugate pair, with
  171.              ALPHAI(j+1) negative.
  172.  
  173.              Note: the quotients ALPHAR(j)/BETA(j) and ALPHAI(j)/BETA(j) may
  174.              easily over- or underflow, and BETA(j) may even be zero.  Thus,
  175.              the user should avoid naively computing the ratio.  However,
  176.              ALPHAR and ALPHAI will be always less than and usually comparable
  177.              with norm(A) in magnitude, and BETA always less than and usually
  178.              comparable with norm(B).
  179.  
  180.      VSL     (output) DOUBLE PRECISION array, dimension (LDVSL,N)
  181.              If JOBVSL = 'V', VSL will contain the left Schur vectors.  Not
  182.              referenced if JOBVSL = 'N'.
  183.  
  184.      LDVSL   (input) INTEGER
  185.              The leading dimension of the matrix VSL. LDVSL >=1, and if JOBVSL
  186.              = 'V', LDVSL >= N.
  187.  
  188.      VSR     (output) DOUBLE PRECISION array, dimension (LDVSR,N)
  189.              If JOBVSR = 'V', VSR will contain the right Schur vectors.  Not
  190.              referenced if JOBVSR = 'N'.
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. DDDDGGGGGGGGEEEESSSS((((3333SSSS))))                                                            DDDDGGGGGGGGEEEESSSS((((3333SSSS))))
  203.  
  204.  
  205.  
  206.      LDVSR   (input) INTEGER
  207.              The leading dimension of the matrix VSR. LDVSR >= 1, and if
  208.              JOBVSR = 'V', LDVSR >= N.
  209.  
  210.      WORK    (workspace/output) DOUBLE PRECISION array, dimension (LWORK)
  211.              On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  212.  
  213.      LWORK   (input) INTEGER
  214.              The dimension of the array WORK.  LWORK >= 8*N+16.
  215.  
  216.              If LWORK = -1, then a workspace query is assumed; the routine
  217.              only calculates the optimal size of the WORK array, returns this
  218.              value as the first entry of the WORK array, and no error message
  219.              related to LWORK is issued by XERBLA.
  220.  
  221.      BWORK   (workspace) LOGICAL array, dimension (N)
  222.              Not referenced if SORT = 'N'.
  223.  
  224.      INFO    (output) INTEGER
  225.              = 0:  successful exit
  226.              < 0:  if INFO = -i, the i-th argument had an illegal value.
  227.              = 1,...,N:  The QZ iteration failed.  (A,B) are not in Schur
  228.              form, but ALPHAR(j), ALPHAI(j), and BETA(j) should be correct for
  229.              j=INFO+1,...,N.  > N:  =N+1: other than QZ iteration failed in
  230.              DHGEQZ.
  231.              =N+2: after reordering, roundoff changed values of some complex
  232.              eigenvalues so that leading eigenvalues in the Generalized Schur
  233.              form no longer satisfy DELCTG=.TRUE.  This could also be caused
  234.              due to scaling.  =N+3: reordering failed in DTGSEN.
  235.  
  236. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  237.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  238.  
  239.      This man page is available only online.
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.